Copyright: © 1996, T. Gitlin


Mailbox-to-Text/HTML Conversion Utility - ©1996, T. Gitlin

This is not free software, even though it is fully functional.  The program has no timers, counters or disabled functions.  You are hereby licensed to use this software for evaluation purposes without charge for a period of 21 days.  If you use this software for more than 21 days, you need to register it.

Registration/Contact Info	Distribution Info
Overview	Command Buttons
General	Select All
Quick Instructions	Deselect All
Technical Notes	Make New Directory
Menu Commands

Save Settings on Exit

Show Tool Tips

About

Tool Bar Commands
Copy Attachments	Extract Messages
Attachment Directory	Examine Status
Options	Change Filetimes
Text	Exit
HTML	Help

Important Legal information:

BY USING THIS UTILITY YOU AGREE TO ALL OF THE STATEMENTS BELOW:

This utility is provided to the user 'as is'.  There are no warranties, either express or implied, with respect to this utility, including but not limited to any warranty of merchantability, fitness for a particular purpose or against any infringement. T. Gitlin does not warrant that the functions in this utility will meet your requirements or that the operation will be error-free, or that any defects in the utility will be corrected.  Further, T. Gitlin does not warrant or make any representations regarding the use of or the results of use of this utility, including software or any documentation provided therein in terms of correctness, accuracy, reliability, or otherwise.  No oral or written information given by T. Gitlin shall create a warranty or in any way increase the scope of this warranty.

Limitation of Liability  - T. Gitlin is not liable for any claims or damages whatsoever including property damage, personal injury, intellectual property infringement, loss of profits, loss of data, or interruption of business, or for any special, consequential, or incidental damages, however caused, whether arising out of breach of warranty, contract, tort (including negligence), strict liability, or otherwise.

Eudora® is a registered trademark of the University of Illinois Board of Trustees, licensed to QUALCOMM Incorporated.  QUALCOMM® is a registered trademark and registered service mark of QUALCOMM Incorporated.

All other service marks and trademarks are the properties of their respective owners.


Quick Instructions

The mailbox files you wish to convert must be in plain text format.  If you are using Eudora, you may need to select 'Compact Mailboxes' from within Eudora to make sure the mailboxes are in plain text format.

1.	On the left side of the window (in the 'Source' frame), click on the drive and double click on the directory where your mailbox files are stored.  Click on individual files to highlight (select) the mailboxes you wish to convert.

2.	On the right side of the window (in the 'Destination' frame), click on the drive and double click on the directory in which to store the extracted files.

3.	Make sure the 'Source' and 'Destination' frames show the proper mailboxes you wish to convert and also show the intended destination directory.  The text in the box in the topmost area of the 'Source' frame shows the number of mailboxes selected and text in the topmost area of the 'Destination' frame shows the selected destination directory.

4.	Click the 'Copy Attachments' button if you want attachments copied along with their corresponding messages.  Click the 'Attachment Directory' button if you have moved the attachments from their original locations (Note: The attachments are not be moved or deleted from their source directory, they are simply copied).

5.	Click the 'Options' button to view the various option settings.  Change them to suit your particular task.

6.	Click the 'Extract Messages' button to process the selected mailbox(es)!


Extract Messages

Clicking this button (or selecting the corresponding menu item), will process the mailboxes that are highlighted in the 'Source' frame and store the individual (extracted) messages in the selected destination directory.

The text box immediately to the left of the 'Extract' button shows a summary of the number and total size of the mailboxes to be converted.  The text box to the right of the button shows the directory in which individual files will be saved.  Double check that the text boxes show the proper number of mailboxes and the correct destination directory before you click the 'Extract' button.

If you want to copy attachments referenced in extracted messages, select the Copy Attachments option.


Copy Attachments

Clicking this button (or selecting the corresponding menu item) will cause the attachments referenced in individual messages to be copied to the same directory as the extracted messages.

Note that the button stays down or pops up when clicked.  When the button is down attachments will be copied; when it is up, attachments will NOT be copied.

Attachments are copied according to the 'Copy attachments that were transmitted' and 'Copy attachments that were received' settings on the Options screen.

Attachments are not moved or deleted from their source directory, they are simply copied.

If you have moved attachments from their original locations, click the 'Attachment Directory' button to specify the directory in which the attachments can be found.

If attachments cannot be found when messages are extracted, warnings are entered in the status list.


Attachment Directory

If you have moved message attachments from where they were originally stored, you need to click this button (or select the menu item) to specify the directory in which you placed them.  The specified directory will be searched for both transmitted and received message attachments.

This button is not active unless the 'Copy Attachments' checkbox is selected.

If attachments cannot be found when messages are extracted, warnings are entered in the status list.


Copy attachments that were transmitted

This option, when selected, will cause attachments referenced in transmitted messages to be copied when the 'Copy Attachments' box on the main screen is selected.

Attachments to be copied are identified by the 'X-Attachment' line contained in the header information of the message.

If you have moved attachments from their original locations, click the 'Attachment Directory' button to specify the directory in which the attachments can be found.

Note that if the same attachment is referenced in multiple messages, only one (the last one referenced and copied) will appear in the destination directory.

If attachments cannot be found when messages are extracted, warnings are entered in the status list.


Copy attachments that were received

This option, when selected, will cause attachments referenced in received messages to be copied when the 'Copy Attachments' box on the main screen is checked.

Attachments to be copied are identified by the 'Attachment Converted' line in body of the e-mail message.

If you have moved attachments from their original locations, click the 'Attachment Directory' button to specify the directory in which the attachments can be found.

Note that if the same attachment is referenced in multiple messages, only one (the last one referenced and copied) will appear in the destination directory.

If attachments cannot be found when messages are extracted, warnings are entered in the status list.


When copying attachments:

These options determine what type of attachments to copy.

There are two check boxes:

Copy attachments that were transmitted

Copy attachments that were received

If you have moved attachments from their original locations, click the 'Attachment Directory' button to specify the directory in which the attachments can be found.


Options

The 'Options' screen allows you to select several different ways the utility should build filenames and also allows you to set some of the general operating modes of the utility.  The button 'Reset to Program Defaults' changes all option values to the original, pre-set defaults.

Extracted Message Filename Options

Include the date sent in the filename

Include the Sender in the filename

Delete illegal characters in filenames

Make the file date the same as the message date

Save files with *** as the file extension

Truncate filenames (subjects) to ** characters

Other Options

When copying attachments:

End of message header determined when:

Store files in HTML format

Strip Enriched Text Formatting (ETF) codes

Strip excess header information

Store files as 'Read Only'

Warn if converting more than *** Kb of files

Track *** for the Status list


Save Settings on Exit

This line, when checked, will cause the options to be saved when exiting the program.  The last options saved are used when the program is run the next time.

Option settings are stored in the registry.  See 'Technical Notes' for more details.


Examine Status

Clicking this button (or selecting the corresponding menu item) brings up a window which shows the status of the conversion after the conversion is completed or canceled.

You may view, print or clear the status list with the buttons on the screen.

Note that status collection is cumulative.  The status for all conversions in a single session are recorded.

Different types of messages can be logged in the status list.  Content of the status list is controlled by the option 'Track *** for the Status list'


Reset to Program Defaults

Clicking this button will set all options to the original program defaults.


Exit

Clicking this button (or selecting the corresponding menu item) exits the utility.

If the 'Save Settings on Exit' option is selected, the current option settings are written to the registry when exiting.


Make the file date the same as the message date

This option, when selected, will force the filetime to be set to the date the message was sent.  Note that the absolute value of the date in the 'Date:' field in the message is used for the filetime.  The filetime is NOT adjusted for the UTC time offset of the sender.  This is done to be consistent with the way Eudora shows the date for messages in mailboxes.

Note that this is a very useful option that allows identification and sorting of messages based on the filetime with other file utilities.

Redirected messages will use date information found in the raw header, NOT the date information in the 'Date:' line.

If a sent date cannot be found in a message (which should rarely happen), the current system date will be used as the filetime.

If the option is not selected, the current system time is used as the filetime.


Include the date sent in the filename

This option, when selected, appends the date sent to the filename (i.e. [12-Jun-96]).

The date format defaults to 'YY-MM-DD'.  If you want to use 'MM-DD-YY' for the date format, select the 'Use MM-DD-YY format (instead of YY-MM-DD)' box.

If you want the date appended at the beginning of the filename, select the 'Put date at the beginning of the filename' box.  Note: If the 'Put date at beginning of the filename' box and the 'Put Sender at the beginning of the filename' boxes are both selected, the 'Sender' option will take precedence.

You may select which characters to use to enclose the appended date.

Note that this option DOES NOT affect the filetime, it only affects the date appended to the filename.  If you want the filetime to be set to the message 'Sent:' date, select the 'Make the file date the same as the message date' option.

Redirected messages will use date information found in the raw header, NOT the date information in the 'Date:' line.

Messages with no valid date information will have 'No Date' appended if this option is selected.


Substitute *** for illegal characters in filenames

This option, when selected, will substitute the chosen character for illegal characters found in a filename.  It is active only if the 'Delete illegal characters in filenames' is NOT selected.

Many message subjects, sender information, and dates have colons, periods, slashes, etc. in the their text, and these characters cannot be used in a filename.

See the Technical Notes section for a listing of illegal characters.


Delete illegal characters in filenames

This option, when selected, will delete illegal characters found in a filename.

When this option is not selected, you may choose characters to substitute for illegal characters with the Substitute *** for illegal characters in filenames option.

Many message subjects, sender information, and dates have colons, periods, slashes, etc. in the their text, and these characters cannot be used in a filename.

See the Technical Notes section for a listing of illegal characters.


Include the Sender in the filename

This option, when selected, appends the sender's name to the filename.

If the 'Use the 'normal' version of the Sender's name' option is selected, the sender's name enclosed in quotes or parenthesis in the message will be used to identify the sender.  If the 'Use the 'normal' version of the Sender's name' is NOT selected, the utility will try to find and use the e-mail address of the sender, which is usually found enclosed in '<>' characters in the message.

If the 'Delete domain info from the Sender's Name' option is selected, the utility will remove any characters after the '@' symbol in the senders name, regardless of whether the 'Use the 'normal' version of the Sender's name' is selected or not.

If you want the Sender appended at the beginning of the filename, select the 'Put Sender at the beginning of the filename' box.  Note: If the 'Put date at beginning of the filename' box and the 'Put Sender at the beginning of the filename' boxes are both selected, the 'Sender' option will take precedence.

You may select which characters to use to enclose the Sender's name.

Messages with no 'From:' line will have 'Unidentified Sender' appended if this option is selected.


Save files with *** as the file extension

This option allows you to select the file extension to use for extracted messages.  You can use one of the pre-defined extensions, or type in one of your own.

Note that if you use the default '.txt' extension, you will be able to simply double-click on an extracted message to open it (assuming you have an application registered for '.txt' files).  Similarly, storing files with an '.htm' or '.html' extension will launch your web browser when you double-click on a file (again assuming you have your browser registered as the application to use for '.htm' or '.html' files).


Truncate filenames (subjects) to ** characters

This option allows you to specify the lengths of filenames (which are extracted 'Subject:' lines).

The length of the filename will be the lesser of the 'Truncate' value OR the actual length of a subject in a message (plus the Sender and Date information, if those options are selected).

The overall filename cannot exceed 255 characters.  See Technical Notes for more information.


Strip excess header information

This option, when selected, strips some of the header information (lines preceding the 'From:', 'Date:' and 'Subject' lines) before saving the extracted messages.

Saved messages will still retain the 'From:', 'Date:' and 'Subject' lines when the header is stripped.

Stripping the header will save some space in the destination directory.


Store files in HTML format

This option, when selected, will store the extracted messages in HTML format.  Selecting this option disables the 'Strip Enriched Text Formatting (ETF) codes' option.

Checking the 'Convert Enriched Text Format (ETF) to HTML' box will translate common ETF tokens into their HTML equivalents.  For example, the ETF token "<bold>" becomes "<b>", "<italic>" becomes "<i>", etc.  Please be aware that not all ETF tokens have HTML equivalents - ones that do not are inserted in the HTML as comments (i.e., "<!token>").  Text in the messages that appears between "<" and ">" symbols that cannot be identified as valid ETF token is inserted in the HTML literally.

If the 'Convert Enriched Text Format (ETF) to HTML' is not checked, text will be scanned for "<" and ">" symbols, and convert them into HTML literals.  This will prevent browsers from treating plain text that happens to include the "<" or ">" as HTML.

Checking the 'Thread messages (include "Re:" links)' box will cause the program to look at each message subject that begins with an 'Re:' or 'RE: ', locate the "parent" message, and insert a hypertext reference to the reply message at the end of the "parent" message.

Hypertext links are inserted for references to http://, ftp:// and www. links.

The Subject, Date and From information will be added to the HTML file, and each individual line of the message will be formatted with breaks as follows:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">

<HTML>

<HEAD><TITLE>(message subject goes here)</TITLE></HEAD>

<h2>Date: (message date/time goes here)</h2>

<h2>(message subject goes here)</h2>

<h2>From: (sender goes here)</h2><hr>

(the first line of message text goes here) <br>

(the next line of message text goes here) <br>

. . .

(the last line of message text goes here) <br>

</HTML>


Warn if converting more than *** Kb of files

This option will show a warning which will allow you to cancel or continue a session if you attempt to extract a large number of messages.

Note that large mailboxes (or a large number of mailboxes) can take some time to convert.  If there are several thousand messages to convert, it will take some time to process the messages since the program must check for repeated filenames each time a message (file) is written to disk.


Track *** for the Status list

This option determines whether every action gets logged, or only exceptions and concerns get logged.

After finishing (or canceling) a conversion, pressing the 'Examine Status' button will display the status list.

If you select 'Everything', the utility will create an entry for each individual file written.  The utility will also create an entry for each attachment copied.  Exceptions and concerns will also be logged.

If only 'Exceptions and Concerns' is selected, the utility will create entries for abnormal situations, such as encountering duplicate filenames, or referencing attachments that could not be found.


End of message header determined when:

This option determines when to flag that an end of an individual message header has been reached.  When the end of a header has been reached, the program stops searching for date, subject or sender information.

If you are positive that lines in the message headers only have a single carriage return/line feed character combination ending each header line, select the 'Blank line found' box.  If you aren't sure, select the 'Status or X-Attachments line found' box.

The entire message content will be saved regardless of the selection of either checkbox.


Show Tool Tips

This line, when checked, will show the toolbar captions when the mouse is moved to a button.  When not checked, the tips are not shown.


Technical Notes

The mailbox files must have a '.mbx' extension for the utility to find them.

The utility assumes that each individual message within a mailbox file has a line that contains 'From ' an '@' character, and a date and time (which is the case with mailboxes created by Eudora, and is a standard for UNIX style mailboxes).

The 'Subject:', 'From:' and 'Date:' fields must begin at the leftmost position of a line (i.e. no preceding characters).  Extracted files use the 'Subject:', 'From:' and 'Date:' lines that are initially encountered in an individual message.  If no 'Date:' line appears in a message, the raw date information contained in the header (applied by the e-mail daemon) is used for setting the filetime or appending date information.

Illegal characters in the filename or extension are either deleted, converted to ASCII spaces, or an optional character is substituted for them.  Illegal characters include any character with an ASCII value less than 32, greater than 126, or any of the following:  \ / : * ?  + " +  < > | .

Any individual message within a mailbox file is truncated at 1000000 lines.  (How long is 'War and Peace' anyway?).

Extracted messages that have been redirected show the original sender as the sender, not the party that redirected the message.  The date for redirected messages is the mailer daemon date.

Before a file is saved, the filename is trimmed so that it will not exceed 255 characters.

Filenames that would be duplicated in the target directory are saved with a numeric identifier that is appended to the filename.  For example, if there are two messages with a subject of 'Re: Notes from Meeting' from 'john doe', the first message will be saved as 'Re: Notes from Meeting (john doe).txt' and the second would be saved as 'Re: Notes from Meeting (john doe)1.txt'

Attachments that would be duplicated in the target directory are not copied.  A summary of the number of duplicate references is entered into the status list for each mailbox after conversion.  You can view the status list by clicking the 'Examine Status' button.

Transmitted attachments are identified by the X-Attachment line in the message.  Paths/names of attachments in the X-Attachment line are assumed to be separated by semicolons.

Options are stored in the registry under HKEY_CURRENT_USER/Software/VB and VBA Program Settings/mail2txt

See the Enriched Text Formatting section (ETF) for more details on ETF

The first parent message found is used when threading HTML messages.  Threading is performed at a mailbox level (i.e. if multiple mailboxes are converted, each one is individually threaded - parents in one mailbox will not be referenced to "Re:" messages in a different mailbox).

The results of setting filetimes can be different based on the file system structure.  Win95 and NT both record file creation time, last access time, and last write time for each file.  However, the NT File System (NTFS) stores file creation, last access, and last write times with 100 nanosecond resolution.  The FAT file system records file creation time with a resolution of ten milliseconds, last access time with a resolution of one day, and last write time with a resolution of two seconds. When modifying a filetime, the FAT file system rounds file creation time and last write time up to the nearest tick, and rounds last access time down to 12:00 AM of the current day in local time.


Select All

Clicking this button will select (highlight) all of the files shown in the window.


Deselect All

Clicking this button will deselect (clear highlight) all of the files shown in the window.


Make New Directory

Clicking this button allows you to create a new directory or subdirectory.

You must specify a path directly off an existing (or root) directory.  For example, if 'C:\TEST' exists (and 'C:\TEST\MAIL' does not), you can create 'C:\TEST\MAIL', but you cannot create 'C:\TEST\MAIL\CONVMAIL'.  If you wish to create lower level subdirectories, use another method before you extract messages.


Store files as 'Read Only'

This option, when checked, will cause the files to be flagged as read only.

Marking the files as read only helps prevent inadvertent changes to the files.


Strip Enriched Text Formatting (ETF) Codes

This option, when checked, will cause the text to be processed to remove any ETF codes.

This option is not available when the 'Store files in HTML format' option is checked.


Help

Clicking this button (or selecting the corresponding menu item) brings up this help file.


About

This line, when selected, shows utility version and author information.

It also shows a cool picture of the author at the Grand Canyon some years back.


Text

This button, when clicked down, will clear the 'Store files in HTML format' option and sets the 'Save files with *** as the file extension' to 'txt'.

Note that the button stays down or pops up when clicked.  When the Text button is clicked down, the HTML button will pop up.


HTML

This button, when clicked down, will check the 'Store files in HTML format' option and sets the 'Save files with *** as the file extension' to 'htm'.

Note that the button stays down or pops up when clicked.  When the HTML button is clicked down, the Text button will pop up.


Registration/Contact Info

You are hereby licensed to use this software for evaluation purposes without charge for a period of 21 days.  If you use this software after the 21 day evaluation period you must register it.  Payment must be in the form of US dollars.  If sending a check, it must be drawn on a US bank.

Quantity discounts and site licensing are available.

Please mail either $5.00 (standard registration fee) or $10.00 (extended registration fee which qualifies you for automatic updates and additional documentation via e-mail) to:

T. Gitlin

P.O. Box 491

Glenn Dale, MD 20769-0491

USA

e-mail:	tgitlin@erols.com

URL:	http://www.erols.com/tgitlin

Feel free to send an e-mail if you have any comments, bug reports or enhancement requests.

If you register with the $10 fee, make sure you supply an e-mail address so that I can e-mail updates and/or fixes to you along with documentation that describes the utility in more detail.

Note: I do not add customers to any 'junk mail' lists or give customer information to others.

Thank you very much for sending in your fee!!


Distribution

You may make and distribute as many copies of this software as you wish as long as you distribute all of the unmodified source files (including this help file).


General

This program is a utility that allows you to bulk extract messages from Eudora mailbox files (as well as UNIX compatible mailboxes) and store the extracted messages as pure text or HTML files.  The utility also includes a separate function to set filetime information to any value desired (within operating system limitations).

The source files must have an extension of '.mbx' for the utility to locate them.

Storing messages individually as pure text files allows you to view and manipulate the messages with standard file utilities, independent of platform.  You don't need an e-mail client to view the messages.  Storing messages as HTML files allows you (and others) to view the messages using a Web browser.

The utility is a 32 bit application written to function under Win95/NT.  It will not run under Win3.x.  It has been tested with Eudora Pro versions 2.2 and 3.0, but it should work with earlier versions of Eudora Pro and Eudora Lite.

What makes this utility unique is that it can process individual or multiple mailboxes, extract each e-mail message, copy any attachments, and store the e-mail messages as individual files.  The files will have the 'Subject' of the message as the filename, and the date of the file is set to the 'Date' sent of the message.  The sender can also be identified in the filename if you desire.

This utility allows e-mail messages to be treated, stored, archived, filed, sorted and saved in many different ways.  For example, if you want to put e-mail messages on a server for others to view,  you can simply extract the messages from your mailbox file(s) to a server.  Extraction to network drives is also supported.

You could also use your 'zip' utility to take store your individual e-mail messages in a greatly compacted form to preserve disk space for archival purposes.


Change Filetimes

Clicking this button (or selecting the corresponding menu item) brings up a screen which allows you to set filetimes to any value you wish (within operating system limitations).  It is useful for many purposes, including re-setting filetimes which have been modified from their original times.

Use the left side of the screen to select individual or multiple files by first selecting the drive, the directory, the file mask, and then the files themselves.

After selecting the files, enter the time information you want in the boxes next to the 'Creation', 'Last Access' and 'Last Written' labels.  You can click a 'Now' button to insert the current time.

Use the 'Set All times to:' buttons to copy time information from one time to another.  You can click the 'Now' button to insert the current time in all three times.  For example, to set all time information to '1996 1/1 12:00:00', entered the value in the 'Creation' field, then click the 'Creation' button in the 'Set All times to:' frame.

The 'Year' must be between 1980 and 2099, and the number of days must be valid for the month and year selected.  The day of week stored for a file (such as 'Sunday'), is NOT shown on the screen because it is automatically determined when the time information is written.

Alphanumeric characters in the time information are treated as zeros.

The 'Use Extended Filetime Information' check box allows access to extended fields.  For information concerning constraints of extended filetime information, see the 'Technical Notes' section.

Click the 'Write Filetimes' button to write the desired times to the selected file(s).


Enriched Text Formatting

Enriched Text Formatting, supported by Eudora 3.0 and later, specifies codes for simple text formatting (also called "tokens") that can be inserted into ASCII text.  When viewed by a reader that supports ETF formatting, the codes are stripped and the text is shown (and printed) as formatted text.  The tokens are always surrounded by "<" and ">" characters.

Since the presence of ETF tokens would clutter pure text (or, for that matter, HTML), the option to strip them is allowed.  This utility processes ETF differently depending on the state of the 'Store files in HTML format' and 'Strip Enriched Text Formatting (ETF) codes' options.

The ETF tokens currently recognized by this utility are:  <nofill>, </nofill>, <bold>, </bold>, <italic>, </italic>, <fixed> ,</fixed> ,<excerpt> ,</excerpt> ,<x-rich> ,</x-,rich>, <underline>, </underline>, <smaller>, </smaller> ,<bigger> ,</bigger> ,<center> ,</center> ,<flushright> ,</flushright> ,<paraindent> , </paraindent> ,<param>, </param>

Note:  The <param> and </param> tokens have a special meaning, and text falling between the tokens is removed when stripping ETF tokens from text.

Unrecognized tokens are not removed from the text when stripping ETF.


A file containing a collection of individual messages.  Mailbox files must have an '.mbx' extension to be used with this utility (i.e. 'in.mbx, 'out.mbx', and 'trash.mbx' are valid mailbox file names).


Eudora® is an e-mail client which sends and retrieves e-mail and stores the messages in UNIX compatible mailbox files.


Any type of file that was included as a separate file (NOT as part of the main body) when an e-mail message was transmitted.  For example, a sender may 'attach' a drawing file, presentation file, or document file to an e-mail message when it is sent. Or, a message recipient may receive an attachment when an e-mail message is retrieved.   Note that Eudora shows special icons when messages have attachments.


Please, please, please register!!! I really tried to make this a useful (and easy to use) utility for you!!


HTML stands for Hypertext Markup Language.  HTML is a standardized language for composing Web pages.